Pidgin
Trac is being migrated to new services! Issues can be found in our new YouTrack instance and WIKI pages can be found on our website.

Version 42 (modified by John Bailey, 17 years ago) (diff)

I THINK this fixes all the screwups hkazemi deemed necessary to introduce.

Using Pidgin

  1. All Platforms
    1. How do I use AIM, MSN, Yahoo!, Jabber/XMPP, ICQ, or any other protocol?
    2. How do I set a buddy icon or avatar?
    3. How do I make Enter make a newline and Ctrl+Enter send?
    4. How do I make Pidgin use emacs-like keybindings?
    5. How do I bind keystrokes to menu items?
    6. How do I make Escape close conversation windows?
    7. How do I change the language for the Highlight Misspelled words option?
    8. How do I register for a new account?
    9. How can I unblock someone?
    10. How does Pidgin decide which saved statuses to show in the status selector?
    11. Why are no states listed when I go to set a state for Auto Away?
    12. Why are the status icons so big?
    13. What happened to my timestamps? Can I change them?
    14. What is a "Buddy Pounce"?
    15. Can I use Pidgin for e-mail, blogging, an RSS feed, or something else …
    16. How do I use/make smiley themes?
    17. Can I "skin" Pidgin?
    18. How do I change the font Pidgin uses? The background color?
    19. Can I turn the tray icon off?
    20. Can I import or export my buddy list?
    21. Why are my logs combining the logs of several of my buddies?
    22. Where did my buddy go? I just tried to change its group and it …
    23. Can I group buddies by their owner, like Trillian's or Miranda's …
    24. What do those colors in the conversation tab mean?
  2. Windows Specific
    1. How does Pidgin for Windows determine which language to use?
    2. Where are my settings and data (including logs) saved?
    3. How do I run multiple instances of Pidgin on Windows?
    4. What should I do if Pidgin Crashes?
    5. Why can't I connect? My firewall is configured to allow Pidgin access.
    6. Why did my smiley theme disappear after I upgraded Pidgin?
    7. How do I change the look and feel?
    8. What is a gtkrc file and where can I find it?
    9. Where is my .purple directory?
    10. Running Windows Pidgin From a USB Drive
    11. Can I make Pidgin transparent/translucent?
    12. Can I make Pidgin or its instant message windows always stay on top?
    13. Can I use Pidgin for Bonjour (Link-Local Messaging)?
  3. Linux and Unix-like platforms
    1. Where are Pidgin's settings and logs?
    2. How do I get sound to work correctly?
    3. How do I make Pidgin use ALSA or OSS for playing sounds? What does …
    4. Why does Pidgin use the same WM_CLASS for every window?
    5. How do I change the look and feel?
    6. Can I make Pidgin transparent/translucent?

All Platforms

How do I use AIM, MSN, Yahoo!, Jabber/XMPP, ICQ, or any other protocol?

Use the Account Editor (Accounts->Add/Edit?) to add the account of the appropriate messaging service. Use the checkbox in the account editor to enable the current account.

How do I set a buddy icon or avatar?

We call all user pictures, avatars, etc. buddy icons. There are two ways to set one for yourself:

  • Global - This will affect all of your accounts. On the Buddy List window, beside the status selector at the bottom, there is an area that will have a generic photo icon if you have no icon set. You can click that and select an icon from there. The icon will take effect for all accounts you have configured in Pidgin.
  • Per-account - This will affect only the account you modify. Go to Accounts->your account->Edit Account. On that dialog, check the box labeled "Use this buddy icon for this account:", then click the leftmost button below that checkbox. Select your buddy icon.

In either case, the file must be smaller than 4KB to work on AIM and XMPP. It can have any dimensions, and can be in any format. However, if you wish Windows users to see it, it must be in a format Windows understands, such as .bmp, .gif, and .jpg. Pidgin will attempt to scale icons to fit within these constraints, but it is not always possible to do so.

The following dimension guidelines are believed to be accurate as of June 2007:

ProtocolDimensionsFormatFile Size
AIM48x48 to 50x50gif, jpg, bmp, ico7168 bytes (7.0KB)
ICQ48x48 to 50x50gif, jpg, bmp, ico7168 bytes (7.0KB)
Yahoo||96x96png, gif, jpg
XMPP (including Google Talk)32x32 to 96x96png, gif, jpeg8191 bytes (one byte short of 8.0KB

Pidgin itself (for the chat window) will scale icons up to 48x48 or down to 50x50. In general, to maintain the aspect ratio, you should begin with a square icon.

How do I make Enter make a newline and Ctrl+Enter send?

Locate or create your gtkrc-2.0 file and insert: 

binding "my-bindings"
{
    bind "Return" { "insert-at-cursor" ("\n") }
    bind "<ctrl>Return" { "message_send" () }
}
widget "*pidgin_conv_entry" binding "my-bindings"

How do I make Pidgin use emacs-like keybindings?

Locate or create your .gtkrc-2.0 file and insert the following: 

gtk-key-theme-name = "Emacs"

You will need to restart Pidgin when you have finished. Note that this will affect other GTK+ applications as well.

How do I bind keystrokes to menu items?

Locate or create your gtkrc-2.0 file and insert: 

gtk-can-change-accels = 1

After coercing Pidgin into rereading this file (for instance, by restarting it), you can hover over a menu item and hit the keystroke you want to bind to it, and your wish will be granted! (You might want to turn off gtk-can-change-accels again when you're done, since it's pretty easy to bind keys by mistake with it turned on.)

(If you're a Gnome user, you should set the /desktop/gnome/interface/can_change_accels key with gconf-editor instead. You don't need to restart Pidgin for this to take effect.)

How do I make Escape close conversation windows?

Locate your .purple directory, and open the accels file within it. Uncomment or add the following line: 

(gtk_accel_path "<main>/Conversation/Close" "Escape")

This must be done while Pidgin is not running.

How do I change the language for the Highlight Misspelled words option?

Pidgin currently only supports spell checking in your locale language. This is because gtkspell 2 does not offer a good way for us to know which dictionaries are available or to switch between them. This functionality has long been promised for gtkspell version 3, which has been delayed somewhat indefinitely. See ​gtkspell.sf.net.

There is, however a simple plugin called ​switchspell that can change the spell check language on a per-buddy basis.

How do I register for a new account?

This depends on the protocol.

How can I unblock someone?

See the "Privacy" option under the "Tools" menu in the Buddy List.

How does Pidgin decide which saved statuses to show in the status selector?

Pidgin shows six "popular" saved statuses in the status selector. These are your six most recently used statuses, offset by a weight. Pidgin sorts all your saved statuses by the timestamp when they were last used. And then, for each time you've used a status, the timestamp is increased by one day.

If you are upgrading from 1.x or lower, Pidgin is unable to determine which are the most popular states, as these older releases did not save that information. As a result, the initial contents of the menu will be somewhat random. It will settle over the first few uses of (distinct) states into the behavior described above.

Why are no states listed when I go to set a state for Auto Away?

Pidgin can only use saved states for Auto Away. You need to create and save a named state first.

Why are the status icons so big?

We believe that, by adding a second line of text to each buddy list entry, we're able to show more information about each buddy on the buddy list. The "Big List," as we call it, shows status text and idle time concisely and attractively. Most importantly, it puts the buddy icon in the list, making it far easier to locate buddies within a large list where names are harder to pick out than images. Due to the increased usability of this interface, we have made it the default.

We are aware that some people feel more comfortable using an interface more similar to IM clients they may have used in the past. The 'Big List' can be disabled by un-checking "Show buddy details" in the Buddies menu.

What happened to my timestamps? Can I change them?

As of 2.0.0, timestamps follow the system locale. This is a significant difference from previous versions of Pidgin, and though it was requested more than once, we know it will prove to be a controversial decision. Fortunately for all of you out there, we also provide plugins to change it.

The two plugins we provide are the Timestamp plugin and the Message Timestamp Formats plugin. Timestamp allows you to have iChat style timestamps, but it is implemented to behave slightly differently. The Message Timestamp Formats plugin allows you to manipulate the timestamps in a couple different ways, such as restoring 24-hour timestamps and/or causing all timestamps to have dates in them.

What is a "Buddy Pounce"?

Pidgin introduced buddy pounces a few releases before AOL came out with "Buddy Alerts." Despite this, you could think of a buddy pounce as an alert and get an idea of the most minimal use of a buddy pounce. In reality, a buddy pounce is much like a macro, or a recorded action. When you set a pounce on someone, you can choose from a number of events, such as sign on or status change, and then you choose from a number of actions. These actions include everything from playing a sound (like an alert would do) to sending a message to the person, to executing a command. This action will occur the next time pidgin detects the event, i.e. the next time the person in your buddy list who you have pounced signs on.

No, you can't. We get requests for this often, but Pidgin is indeed a messaging client. Aside from the capabilities each protocol may support, the Pidgin developers have no intention to turn Pidgin into a multi-feature Internet client capable of doing everything under the sun. We also won't be helping to develop plugins to turn it into that. There are many Internet applications available for Linux, Windows, or whatever operating system you use that would undoubtedly do a better job.

Note that ​LiveJournal provides an XMPP messaging service which makes it possible to make entries to your blog via IM, no matter what XMPP-supporting IM client you use.

How do I use/make smiley themes?

See the page on smileys.

Can I "skin" Pidgin?

The UI can be customized using GTK themes and by Smiley Themes. Application-specific skins will never be supported by Pidgin. This seems to confuse a lot of users, so here's an attempt at an explanation.

Themes allow you to change font size, font face, the color of different elements of the UI, and sometimes their shape. All of this is perfectly reasonable, and encompasses the range of configuration that most users are requesting. Skins go beyond this. Skins allow you to move and possibly suppress different elements of the UI that the programmers have added for specific reasons.

In so doing, skins create a support nightmare. The developer, talking to the user, cannot be sure that the user sees the same interface. Is it a bug that the user cannot see how to change font size, or is the user's skin suppressing that widget? This is an unacceptable situation.

Conversely, while themes allow some silliness, for instance setting the background to the same color as the font, the results are relatively easily foreseen and avoided by theme authors. Further, by using the existing GTK theme mechanism, we gain two advantages:

  1. We don't have to write it ourselves. Were we to write our own mechanism, we would be adding overhead in both the run time and the time necessary to debug.
  2. We have a built in way of debugging theme problems, by checking if the same bug exists with other GTK programs.

Lastly, since GTK themes only allow acceptable modifications, we do not have to worry that a user isn't seeing part of the UI because it is either showing or not showing because of our code.

Themes and information on using them can be found at ​http://themes.freshmeat.net, ​http://art.gnome.org, or by searching on your favorite search engine, such as Google.

How do I change the font Pidgin uses? The background color?

The font preference in Pidgin applies only for the formatting of outgoing messages on those protocols which support said formatting. The display fonts used by the rest of Pidgin are those specified by GTK+, the toolkit we use to create the user interface. To change this font, you need to edit your ~/.gtkrc-2.0 file. On Windows, this file is located at C:\Documents and Settings\username\.themes\Default\gtk-2.0\gtkrc. If that file does not exist, simply create it.

As an example, you can put this into .gtkrc-2.0 to change the font size for all GTK+ applications: 

# Sets the font used by all gtk applications.
gtk-font-name = "Verdana 9"

Alternatively, you can do this to change the font size for other elements: 

# This is the style section.  You need this for the examples below.
# If you are going to copy the example, copy the entire block,
# including the "{" and "}" lines.
style "imhtml-fix"
{
    font_name = "Sans 10"
}

# This will apply the font style just shown to various components.
# If you are going to copy the example, copy the line that does
# what you want.

# Conversation entry box--where you type.
widget "*pidgin_conv_entry" style "imhtml-fix"

# Conversation history pane--where you read the conversation.
widget "*pidgin_conv_imhtml" style "imhtml-fix"

# Log viewer--where you read stored logs
widget "*pidgin_log_imhtml" style "imhtml-fix"

# formatting-capable entry areas (IMHtml widgets) in request dialogs
widget "*pidgin_request_imhtml" style "imhtml-fix"

# formatting-capable notification areas in dialogs (again, IMHtml widgets)
widget "*pidgin_notify_imhtml" style "imhtml-fix"

Background colors can be changed similarly, by finding the correct widget names and setting appropriate bg elements. Other widgets in Pidgin can be controlled in a similar manner.

You could also switch GTK+ themes. Themes and information on using them can be found at ​http://themes.freshmeat.net, ​http://art.gnome.org, or by searching on your favorite search engine, such as Google.

Can I turn the tray icon off?

Yes. By default the tray icon will load if you have a Notification Area or a System Tray in your desktop environment. Look at the Interface tab in Tools->Preferences. Change the 'System Tray Icon' setting to 'Always', 'Never', or 'On unread messages' as you prefer.

Can I import or export my buddy list?

Not with Pidgin alone, but the ​Purple Plugin Pack provides the ​List Handler plugin, which adds some importing and exporting capabilities.

Why are my logs combining the logs of several of my buddies?

It's likely you have inadvertently combined some buddies into contacts when you did not intend to do so. To correct this you need to find which contact the logs are associated with. Right-click that entry in the buddy list and click Expand. Drag out the buddies that do not belong in the contact.

Where did my buddy go? I just tried to change its group and it disappeared!

You inadvertently created a contact from two buddies. Hover over each buddy in the destination group and watch the tooltips that appear. You'll see the "missing" buddy in one of them. Right-click that entry in the buddy list, click Expand, and then drag the buddy that does not belong out to the group. Watch the buddy list carefully; a bar will appear to show you where the buddy will go if you are in the right location.

Can I group buddies by their owner, like Trillian's or Miranda's Metacontacts?

Sure! Right click a buddy on your list and at the bottom of the menu click "Expand". Then just drag other screen names to the same person below it. When you're done, click on the arrow to collapse them. When the contact is collapsed, Pidgin will select a buddy to display based on the status of the buddies in the contact, and their order.

What do those colors in the conversation tab mean?

  • Red - A message is waiting for you
  • Blue - Someone sent a message containing your name
  • Green - The buddy is typing
  • Yellow - The buddy began typing, and then stopped
  • Gray - There has been a join or a part in that chat, or the buddy has signed off

Windows Specific

How does Pidgin for Windows determine which language to use?

For the user who installed Pidgin, the language selected during installation will be the default. This can be overridden by setting the PIDGINLANG environment variable (for example, PIDGINLANG=de). If neither of these are specified, it will fall back to the default Windows user locale setting.

Where are my settings and data (including logs) saved?

Data is stored in your user's "Application Data" directory in a .purple subdirectory. The location of this will vary according to your setup and version of Windows.

  • For Windows 2000/XP/Vista(?), entering %APPDATA% in your Windows Explorer address bar will take you to the right directory (probably something like C:\Documents and Settings\username\Application Data).
  • For Windows 98/ME it will be something like C:\Windows\Profiles\username.

This can be overridden by setting the PURPLEHOME environment variable.
Logs are stored in a subdirectory called logs.

How do I run multiple instances of Pidgin on Windows?

Pidgin will, by default, prevent multiple instances from running simultaneously. You can override this restriction by defining the PIDGIN_MULTI_INST environment variable. If you do this, you may find the -c parameter useful to specify unique configuration directories for each instance (e.g. -c c:\home\.pidgin-alt).

What should I do if Pidgin Crashes?

Follow the instructions here to submit a bug report.

Why can't I connect? My firewall is configured to allow Pidgin access.

We've had a lot of problems with various firewalls, particularly Norton Internet Security (and Symantec Client Firewall). Many firewalls will not fully stop interfering with a program's ability to connect when configured to do so.
For Norton Internet Security, a workaround that seems to work is to add the following ports to the global HTTP Ports list:

  • 443 -> MSN (ssl)
  • 1863 -> MSN
  • 5050 -> Yahoo
  • 5190 -> AIM/ICQ
  • 5222 -> XMPP (including Google Talk)
  • 6667 -> IRC

The Mozilla folks maintain a good Windows Firewall information resource ​here.

Why did my smiley theme disappear after I upgraded Pidgin?

Smiley themes should be installed to the user's .purple directory, not in the location Pidgin is installed to. This means that you install smiley themes only to %APPDATA%\.purple\smileys. Additions to or removals from Pidgin's installation location will be lost during an upgrade.

How do I change the look and feel?

Pidgin doesn't support skinning. It does, however, support GTK+'s use of themes to render the widgets differently. The default theme, MS-Windows, is designed to fit in with Windows. The GTK+ Runtime installer now includes a utility, accessible from the Start Menu, to change the theme. If you'd simply like to change the smilies used in your chats, take a look at the page on smilies.

Themes and information on using them can be found at ​http://themes.freshmeat.net, ​http://art.gnome.org, or by searching on your favorite search engine, such as Google.

What is a gtkrc file and where can I find it?

The windowing toolkit that Pidgin uses, GTK+, is configurable via a text file.

There is a global file found in the etc\gtk-2.0 directory your GTK+ Runtime install directory (C:\Program Files\Common Files\GTK\2.0, by default). There is also per-user file (named .gtkrc-2.0) in your user's home directory, the location of this varies according to the version of Windows you're using and the configuration.

  • For Windows 2000/XP/Vista(?), entering %USERPROFILE% in your Windows Explorer address bar will take you to the right directory (probably something like C:\Documents and Settings\username).
  • For Windows 98/ME it will be something like C:\Windows\Profiles\username.

Note that Windows Explorer will not allow you create a file that starts with a period; you'll need to use a text editor or rename the file in a cmd shell.

It is recommended that you edit your per-user file instead of the global file as the global file will be replaced when GTK+ is upgraded.

Where is my .purple directory?

It is in C:\Documents and Settings\username\Application Data Note, that things within this directory can only be edited when Pidgin is not running.

Running Windows Pidgin From a USB Drive

It is relatively easy to set up Pidgin to run from a USB Drive. Most of Pidgin is very good about not assuming that it is installed; a slightly customized launcher makes it all come together nicely.
The way that this is set up, other GTK+ applications can use the same GTK+ runtime.

  • How to setup your USB-Drive Pidgin
    • Download and Install Pidgin
    • Prepare your USB Drive: (This assumes that your USB Drive is U: for the purpose of explanation)
      • Create a directory: U:\Programs (This can be whatever you want, the idea is that GTK and Pidgin are at the same level)
      • Create GTK and Pidgin directories in this directory.
    • Copy a minimal part of your Pidgin installation to the USB Drive from the installed instance. The directory structure stays the same, but we don't need everything that is included in the standard installation.
      • Copy the whole pixmaps and sounds directories.
      • Create a U:\Programs\Pidgin\plugins directory and copy the contents of the installed Pidgin\plugins directory into it excluding perl.dll, tcl.dll.
      • If you want to use a language other than en_US, create a U:\Programs\Pidgin\locale directory and copy any language directories that you want from your installed Pidgin\locale directory.
      • Copy the contents of your root installed Pidgin directory except pidgin.exe, pidgin-uninst.exe, and if you don't want spell-checking support, libgtkspell.dll.
      • Download pidgin-portable.exe (use gaim-portable.exe for 2.0.0beta4-6 or this version for versions older than 2.0.0beta4) and put it in U:\Programs\Pidgin. The file uses the same source as the standard pidgin.exe, the difference being that when it was compiled PORTABLE was defined which causes some of the initialization to be done differently.
    • In the same spirit, create a minimal GTK+ runtime installation from your GTK+ installation.
      • Copy the bin and etc directories to your U:\Programs\GTK directory.
      • Create a U:\Programs\GTK\lib directory and copy the contents of the installed GTK+ runtime's lib directory, except the locale subdirectory.
      • If you want to use a language other than en_US, create a U:\Programs\GTK\lib\locale directory and copy any language directories that you want from your installed GTK+ runtime's lib\locale directory.
    • If you want spell-checking support, you will also need to create a minimal ASpell runtime installation from your ASpell installation.
      • Create a U:\Programs\Aspell directory with a bin subdirectory.
      • Copy aspell-15.dll into your ASpell bin directory.
      • Copy the data and dict subdirectories into U:\Programs\Aspell.

You are done! Running U:\Programs\Pidgin\pidgin-portable.exe will cause pidgin to run off the USB Drive, saving the settings, logs and etc. to U:\Programs\.purple.

Can I make Pidgin transparent/translucent?

You can make Pidgin translucent in most versions of Windows using the "Transparency" plugin that ships with Pidgin for Windows. You can also use the free Windows utility ​PowerMenu ​(alt) to give transparency capability to any window including Pidgin and its IM windows.

Can I make Pidgin or its instant message windows always stay on top?

If you just want the buddy list to always be on top, you can dock it to the side of your desktop. Otherwise you can use the free Windows utility ​PowerMenu ​(alt) to give 'Always On Top' capability to any window including Pidgin and its IM windows.

As of version 2.0.2, Pidgin for Windows supports Bonjour. You must have Apple's ​Bonjour for Windows installed for the Bonjour protocol to appear in the protocols list.

Linux and Unix-like platforms

Where are Pidgin's settings and logs?

Because Pidgin is a libPurple client, it stores its settings and logs in ~/.purple.

How do I get sound to work correctly?

Pidgin uses gstreamer to play sounds. Playing sounds directly through esound or arts is no longer supported. To compile Pidgin with support for gstreamer you need libgstreamer0.10-dev and its dependencies. These packages are named differently on different platforms. If you do not wish to install these packages you can also just change your sound playing method in preferences to Command and use esdplay %s or artsplay %s.

How do I make Pidgin use ALSA or OSS for playing sounds? What does the "Automatic" option do?

The "Automatic" option lets gstreamer pick how the sounds are played. You can use the gstreamer-properties tool to control this if you use GNOME.

Why does Pidgin use the same WM_CLASS for every window?

Both strings in the WM_CLASS property are supposed to be the same for all windows in the same instance of an application. ICCCM states that one is meant to be the same for all instances of the application and the other is meant to be unique to that instance of the application. ICCCM also states, "If a client has multiple windows with identical WM_CLASS and WM_NAME properties, then it should provide a WM_WINDOW_ROLE property."

GTK+ sets these WM_CLASS values for us so that they are unique for Pidgin instances, and the documentation for the gtk_window_set_wmclass function says explicitly not to use it for anything else. Pidgin uses the WM_WINDOW_ROLE hint to differentiate windows. If your window manager is having problems differentiating between Pidgin windows, please ensure it uses the WM_WINDOW_ROLE hint per the ICCCM.

How do I change the look and feel?

Pidgin doesn't support skinning. It does, however, support GTK+'s use of themes to render the widgets differently. If you'd simply like to change the smilies used in your IMs and chats, take a look at the page on smilies.

Themes and information on using them can be found at ​http://themes.freshmeat.net, ​http://art.gnome.org, or by searching on your favorite search engine, such as Google.

Can I make Pidgin transparent/translucent?

It is not possible to make Pidgin translucent in Linux and other platforms that use X11.

The X.org X11R6 server provides a COMPOSITE extension that allows applications to have true translucency, but it is X.org-specific and it requires support at the GTK+ level (if it is to be per-widget). We do not wish to support this form of translucency until it is supported by GTK+. We also do not wish to implement the pseudo-translucency offered by other programs (by copying a section of your background image, tinting it, and plastering it onto a Pidgin window).

All information, including names and email addresses, entered onto this website or sent to mailing lists affiliated with this website will be public. Do not post confidential information, especially passwords!